<html>
<!-- $LastChangedDate: 2009-11-07 22:56:33 -0500 (Sat, 07 Nov 2009) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - Input Module</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - Input Module</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Overview'>Overview</a></li>
  <li><a href='#Device Class'>Device Class</a></li>
  <li><a href='#Actions'>Actions</a></li>
  <li><a href='#Input Queue'>Input Queue</a></li>
  <li><a href='#Joystick'>Joystick</a></li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Overview'></a>
<h2>Overview</h2>
<p><!--date-->[2009/11]</p>
<p>
The low-level input module consists of Device classes for keyboard, joystick, and mouse.
The purpose is to abstract input devices as a system-neutral event queue.
The input module defers final responses to higher-level modules.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Device Class'></a>
<h3>Device Class</h3>
<p>
A Device class consists of:
</p>
<ul>
  <li>system-specific code to enable and access device</li>
  <li>a device-specific Event struct</li>
  <li>input queue</li>
  <li>broadcasting events to listeners when enqueued</li>
</ul>
<pre>
+------------------------------------------------------------------+
| base template   -->  sys-neutral     -->  private sys-specific   |
| template class       singleton/factory    instance               |
+------------------------------------------------------------------+
| Device          -->  KeyboardDevice  -->  KeyboardDevice[System] |
|                      JoystickDevice  -->  JoystickDevice[System] |
|                      MouseDevice     -->  MouseDevice[System]    |
+------------------------------------------------------------------+
</pre>
<p>
KeyboardDevice etc are a special kind of Singleton that acts like a Factory
by instantiating a system-specific derivative of itself.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Actions'></a>
<h3>Actions</h3>      
<ol>
  <li>Devices are initially disabled to let program become ready.</li>
  <li>The singletons KeyboardDevice etc instantiate a system-specific derivative of themselves.</li>
  <li>A Device object reads input from its device-driver.</li>
  <li>Creates an system-neutral Event struct.</li>
  <li>Puts an Event into its queue.</li>
  <li>Broadcasts to registered listeners that an Event is ready in its queue.</li>
  <li>Alternatively, the consumers can poll the input queue instead of registering a listener.</li>
  <li>Input queue might overflow older events (on slow systems).</li>
</ol>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Input Queue'></a>
<h2>Input Queue</h2>
<p><!--date-->[2004/11..2009/11]</p>
<p>
A Device class has an <i>input queue</i>.
Once enabled, one consumer is needed to drain the input queue.
A consumer can be either an "event listener" or a "poller".
The problem of chaining listeners/pollers isn't addressed in this design.
</p>
<p>
Once a Device is enabled, it will actually remain enabled even if Device::Enable(false) is called.
The device will be <i>logically disabled</i> by disabling the software input queue, not the hardware device.
</p>
<p>
By design, the input queue has a tiny capacity:
it will overflow after a few events remain enqueued.
The reason is to make the program seem more responsive
by giving priority to the most recent input events.
If the queue was large, the program would keep processing
events that were several seconds old and so would respond too slowly.
</p>
<h3>System-Specific</h3>
<p>
Linux joystick driver queues events.
Windows joystick driver samples the joystick's current state.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Joystick'></a>
<h2>Joystick</h2>
<p><!--date-->[2008/01..2009/11]</p>
<p>
There are two unrelated Joystick classes:
input::JoystickDevice and <a href='module_control.html#Joystick'>control::Joystick</a>.
control::Joystick is the consumer of events enqueued by input::JoystickDevice.
control::Joystick has higher-level functionality
(such as joystick calibration and controlling the <i>current craft</i>).
</p>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Sat Nov  7 14:51:52 CST 2009
<!-- hhmts end -->
</font>
</p>

</body>
</html>
